Skip to content

integration-proxy: public self-hosting guide (SELF_HOSTING.md), Dockerfile, host-agnostic README (#79) - #131

Merged
michielbdejong merged 2 commits into
mainfrom
claude/issue-79-self-hosting-guide
Sep 24, 2026
Merged

michielbdejong merged 2 commits into
mainfrom
claude/issue-79-self-hosting-guide

Conversation

@michielbdejong

Copy link
Copy Markdown
Contributor

Closes #79.

Adds integration-proxy/SELF_HOSTING.md, the public guide that the atomic-server connect UI links to (per Michiel's decision on ontola/atomic-server#1700: self-hosted servers default to atomic.place's proxy). Its URL is fixed at https://github.com/ontola/atomic-plugins/blob/main/integration-proxy/SELF_HOSTING.md.

  • Running it:
    • cargo install atomic-integration-proxy --version 0.2.0 --locked; the crate already ships the integration-proxy binary;
    • a minimal Dockerfile that builds the pinned crates.io version and runs as non-root;
    • a systemd unit.
  • Configuration:
    • DATABASE_URL and sslmode: tested against Postgres 16. The default prefer works locally but can be downgraded to plaintext across a network, so use require there;
    • ENCRYPTION_KEY: there's no rotation, and changing it drops every connection;
    • SESSION_SECRET;
    • BASE_URL, which must be exact, with Caddy and nginx examples;
    • CATALOG_PATH, including pinning the catalog to a commit, which was tested;
    • REVOKED_SUBJECTS and ALLOWED_AGENTS: if every ALLOWED_AGENTS entry is invalid, nobody is admitted.
  • OAuth apps: registering your own per platform, with the callback <BASE_URL>/oauth/<platform>/callback and the exact OAUTH_<PLATFORM>_* variables.
  • Pointing clients at your proxy:
    • atomic-server: --integration-proxy-url / ATOMIC_INTEGRATION_PROXY_URL (#1702, still open);
    • the data browser: Settings → Integrations, stored per browser in localStorage, with a build-time default from VITE_INTEGRATION_PROXY_URL;
    • the two settings are separate, and nothing syncs them yet.
  • Operations: upgrades, backups (the database and ENCRYPTION_KEY together), and /healthz monitoring. /healthz has no internal timeout, so monitors must set one.
  • README: the Heroku-specific parts (TLS, DATABASE_URL, callbacks) are made host-agnostic, and the Heroku section is renamed to describe the localthought.io deployment.

Not verified: the systemd unit is checked with systemd-analyze verify only; the Caddy and nginx configs, other Postgres versions and Postgres with TLS are untested; no live OAuth connect was made; and the providers' console links and quirks weren't re-checked against their current docs. The guide says all of this.

No Rust code changed.

🤖 Generated with Claude Code

Michiel de Jong and others added 2 commits September 24, 2026 16:22
Builds atomic-integration-proxy from crates.io (PROXY_VERSION, --locked)
into a debian:bookworm-slim image with libssl3 and ca-certificates, running
as a non-root user. The build context is unused (.dockerignore excludes
everything). Not packaged in the crate (Cargo.toml include list) and not
built in CI; tested locally: build, start against PostgreSQL 16, /healthz,
/catalog. Refs #79.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SELF_HOSTING.md (fixed path, linked from the connect UI): what the proxy
does and doesn't, security model, cargo install / Docker / wrapper crate,
every environment variable, PostgreSQL sslmode behaviour (measured:
prefer falls back to plaintext against a non-TLS server, require refuses
it), ENCRYPTION_KEY generation and the lack of rotation, pinning the
catalog to a commit, ALLOWED_AGENTS, Caddy/nginx, a systemd unit
(systemd-analyze verify only), per-platform OAuth registration with exact
callback and OAUTH_* names, pointing atomic-server (#1702, unmerged) and
the data browser at it, upgrades, backups, /healthz behaviour (measured:
hangs without a timeout while PostgreSQL is paused; recovers after a
restart), limits and what is not verified.

README: link the guide; drop the Heroku-only framing of TLS, DATABASE_URL
and callbacks; label the Heroku section as the localthought.io deployment.
Root README: link the guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong
michielbdejong merged commit 5ad1bc9 into main Sep 24, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

integration-proxy: host-agnostic deployment docs (non-Heroku, local Postgres, SESSION_SECRET)

1 participant